# 08 - 服务层

服务层 (`src/services/`) 封装了所有外部集成，为上层提供统一接口。

---

## 服务总览

```
services/
├── api/            # Anthropic API 客户端
├── mcp/            # Model Context Protocol
├── oauth/          # OAuth 2.0 认证
├── lsp/            # Language Server Protocol
├── analytics/      # 分析与特性标志
├── compact/        # 上下文压缩
├── policyLimits/   # 组织策略限制
├── remoteManagedSettings/  # 远程托管设置
├── extractMemories/  # 自动记忆提取
├── tokenEstimation.ts  # Token 估算
├── teamMemorySync/ # 团队记忆同步
├── tools/          # Tool 编排
├── skillSearch/    # 技能搜索
├── settingsSync/   # 设置同步
├── plugins/        # 插件系统
└── toolUseSummary/ # Tool 使用摘要生成
```

---

## API 服务 (`services/api/`)

### 核心功能

与 Anthropic Claude API 的交互，包括：
- 流式消息创建 (SSE)
- 重试与降级
- Token 计数和费用追踪
- 请求/响应日志

### 关键文件

| 文件 | 作用 |
|------|------|
| `claude.ts` | 主 API 客户端（最大文件之一，~125KB） |
| `errors.ts` | 错误分类（限流、过载、prompt 过长等） |
| `withRetry.ts` | 重试逻辑，支持 fallback |
| `logging.ts` | 请求日志和 usage 统计 |
| `dumpPrompts.ts` | 导出完整 prompt（调试用） |

### 重试策略

```
API 调用失败
  │
  ├─ 429 Rate Limit → 指数退避重试
  ├─ 529 Overloaded → 等待后重试
  ├─ 网络错误 → 重试
  ├─ Prompt Too Long → 触发压缩
  └─ Fallback → 切换到备用端点/模型
```

---

## MCP 服务 (`services/mcp/`)

**Model Context Protocol** — 允许外部服务器向 Claude 提供额外工具和资源。

### 架构

```
Claude Code
  │
  ├── MCP Client ──(stdio/sse)──→ MCP Server A (提供工具 X, Y)
  │
  ├── MCP Client ──(stdio/sse)──→ MCP Server B (提供资源 R1, R2)
  │
  └── MCP Client ──(stdio/sse)──→ MCP Server C (...)
```

### 关键概念

| 概念 | 说明 |
|------|------|
| **MCP Server** | 外部进程，通过 stdio 或 SSE 与 Claude Code 通信 |
| **MCP Tool** | 服务器提供的工具，映射为 `mcp__serverName__toolName` |
| **MCP Resource** | 服务器提供的资源（文件、数据等） |
| **Tool 命名** | `mcp__<server>__<tool>` 格式，确保全局唯一 |

### MCP Tool 集成

MCP 工具被包装为标准 Tool 接口：
- 权限检查照常执行
- 支持 `_meta['anthropic/alwaysLoad']` 标记为始终加载
- 支持 ToolSearch 延迟加载

---

## OAuth 服务 (`services/oauth/`)

处理用户认证流程：

```
用户执行 /login
  │
  ▼
启动本地 HTTP 服务器 (回调接收)
  │
  ▼
打开浏览器 → Anthropic OAuth 页面
  │
  ▼
用户授权 → 回调 URL
  │
  ▼
交换 code → access_token + refresh_token
  │
  ▼
保存到 Keychain / 配置文件
```

Token 管理：
- Access Token → 短期有效
- Refresh Token → 自动刷新
- Keychain 集成 → 安全存储

---

## LSP 服务 (`services/lsp/`)

**Language Server Protocol** 集成，提供代码智能：

| 功能 | 说明 |
|------|------|
| 代码补全 | 上下文感知的代码建议 |
| 跳转定义 | 找到符号定义位置 |
| 查找引用 | 找到符号的所有引用 |
| 诊断信息 | 语法错误、类型错误等 |

LSP 服务器在后台异步启动，不阻塞主流程。通过 `registerCleanup(shutdownLspServerManager)` 确保退出时清理。

---

## 分析服务 (`services/analytics/`)

### GrowthBook 特性标志

```typescript
import { getFeatureValue_CACHED_MAY_BE_STALE } from './services/analytics/growthbook.js'
```

使用 GrowthBook 进行 A/B 测试和特性管理。缓存策略名如其意：`CACHED_MAY_BE_STALE`——值可能不是最新的，但避免了频繁的网络请求。

### 遥测

- OpenTelemetry 集成（延迟加载，~400KB）
- gRPC 导出器（进一步延迟加载，~700KB）
- 事件日志 (`logEvent()`)

---

## 压缩服务 (`services/compact/`)

当对话太长时压缩上下文：

### 自动压缩 (Auto-Compact)

```typescript
const state = calculateTokenWarningState(tokenCount, limit)
// state: 'none' | 'warning' | 'critical'
```

### 压缩流程

```
原始消息历史 (可能 100+ 条消息)
  │
  ▼
选择压缩边界（保留最近的消息）
  │
  ▼
将旧消息摘要化
  │
  ▼
生成 compact boundary 消息
  │
  ▼
新消息历史 = [摘要] + [最近消息]
```

### 响应式压缩 (Reactive Compact)

Feature flag `REACTIVE_COMPACT` 控制。在检测到上下文即将溢出时主动触发，而不是等到溢出才处理。

---

## Tool 编排服务 (`services/tools/`)

### StreamingToolExecutor

支持在 API 流式响应过程中提前开始执行 Tool：

```
API 流: [text] [tool_use_1 开始] [tool_use_1 参数...] [tool_use_1 完成] [tool_use_2...]
                                                        ↓
                                              tool_1 立即开始执行
                                              （不必等所有 tool_use 接收完）
```

### toolOrchestration (`runTools`)

```typescript
import { runTools } from './services/tools/toolOrchestration.js'
```

负责：
- 将 Tool 分为并发安全组和串行组
- 并发组并行执行（最多 10 个）
- 串行组按顺序执行
- 收集所有结果

---

## 策略限制服务 (`services/policyLimits/`)

组织级策略控制：
- API 使用限额
- 可用模型限制
- 功能开关

通过 `isPolicyLimitsEligible()` 判断是否加载，仅企业用户生效。

---

## 团队记忆同步 (`services/teamMemorySync/`)

在团队环境中同步共享的记忆和配置，确保团队成员的 Claude Code 体验一致。